Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d18 / t_ref5.arc / T-REF.DOC < prev next >

Wrap

Text File | 1991-04-28 | 84.8 KB | 2,311 lines

T-Ref 5.03S (Shareware Version) A Source Listing and Cross Referencing Program For Turbo Pascal 4.0 and 5.0 Copyright (C) 1986, 1989 by Synergy Software Solutions P. O. Box 28625 Papillion, NE 68046 CompuServe # 72617,1411 Legal Rights and Issues Synergy Software Solutions (hereafter denoted as SSS) retains all rights of ownership of the product called T-Ref under United States and International laws of commerce. T-Ref is a copyright of SSS. However SSS hereby expressly authorizes the willful distribution of the enclosed software to other indi- viduals or companies. SSS does NOT authorize, nor waive, any other rights provided under the protection of copyright laws, and reserves the right to withdraw distribution rights at any future time. At such time, notice will be given. This Version: T-Ref Version 5.03S is a shareware product. It is NOT a public domain or freeware program. Shareware means that you are given a specific period of time in which to test the product before you are required to register your copy. Thus, if you decide to use T-Ref, you are expected to REGISTER your copy with SSS. SSS gives all potential personal and/or company/corporate buyers a full 60 day trial period in which to determine whether T-Ref is of use to them. At such point, individuals using T-Ref for personal use are expected to register their copy with SSS. Companies and corporations that use T-Ref beyond the 60-day trial period MUST register their copy with SSS, or CEASE use of the product. Special discounts are available for site licensing. Regis- tration fees are noted in the file REGISTER.FRM. Table of Contents Preface T-Ref Light i Package Files i System Requirements i Limitations ii Before Getting Started ii Commitment ii Chapter 1 - Introduction to T-Ref What T-Ref Can Do 1-1 T-Ref's "Driver" Program 1-2 1. File I/O Area 1-2 2. Source Lister Area 1-2 3. Cross Reference Lister Area 1-3 4. Function Keys 1-3 5. Changing the Parameter Settings 1-4 6. Exiting T-Ref 1-5 7. Executing the "Scanner" Program 1-5 8. T-Ref's "Scanner" Window 1-5 Chapter 2 - The Source Lister Activating the Source Lister 2-1 Parameter Options 2-1 Reserved Words and Identifiers 2-1 Line Numbering 2-2 Lexical Level Numbering 2-2 Block Level Numbering 2-3 Block Diagramming 2-3 Auto-Commenting 2-3 Active Procedure/Function 2-4 Header Markers 2-4 Chapter 3 - The Cross Reference Lister Activating the Reference Lister 3-1 Detail Level 3-1 Object Selection 3-2 Scanning Within Conditional Compilation 3-2 Procedural Table Listing 3-2 Code Analysis 3-3 Undeclared Identifiers 3-3 Interpreting the Reference Listing 3-3 Hardwired Identifiers 3-6 Chapter 4 - Common Features Handling Include Files 4-1 Defining Listing Headers 4-1 Page Numbering 4-2 Chapter 5 - I/O Control Features Screen Control 5-1 Printer Control 5-2 File Control 5-3 Chapter 6 - T-Ref Quick Start Backing up T-Ref 6-1 Building the Database File 6-1 Executing T-Ref 6-1 Setting the Default Parameters 6-1 Saving the New Settings 6-3 Chapter 7 - Commercial Version of T-Ref The T-Ref Shell 7-1 The Scanner Program 7-2 The Source Lister 7-2 The Cross Referencer 7-2 PREFACE Welcome to the shareware version of THE BEST source listing and cross referencing program for Turbo Pascal 4.0 and 5.0. But don't take my word for it. You'll see for yourself that it is better than any other shareware program of its type or EVEN any commercial product! And it is offered at a shareware price! It is flexible through its precise and accurate information, and best of all, it's easy to use. Details about what T-Ref can do are part of the program through context-sensitive help windows, so this document file will be fairly short. T-Ref will provide you with details on nearly every option available. T-Ref Light: With the release of this shareware version, I actually now have two different versions of T-Ref. The other version, a commercial ("industrial grade") version, has about a dozen features this version does NOT have. This does not mean that the shareware version suffers some form of malnutrition or a deformity that will restrict your abilities to print and reference your source files. However, some of the advanced features available on the commercial version have been "inhibited". Chapter 7 details the features offered only with the commercial version. Also, the documentation released with this version is meant to be short (due to limited space for distribution purposes) while still giving as much details about the program as neces- sary. A much more comprehensive and complete manual set (nearly 100 pages of material) comes with the $25 and $45 registration levels. This manual documents warnings and errors, provides insights to how to use T-Ref more effectively, and describes some features not documented in this abridged copy. Package Files: The files that come with this shareware version of T-Ref are T-REF.EXE The main driver program T-REFSCN.EXE The scanner sub-program (called by T-REF) T-REF.HLP On-Line Context-Sensitive Help File INITDB.EXE This program builds the database program used by T-Ref T-REF.DOC This document file REGISTER.FRM Registration forms for registering T-Ref System Requirements: T-Ref requires an IBM-PC or compatible system with a minimum of 256K of memory and either MS-DOS or PC-DOS 2.0 or greater. i Limitations: There are a few T-Ref limitations you should first be aware of. These are: 1) The maximum length of an identifier is 20 characters. Longer identifiers will be cut to 20 characters. 2) Diagram blocking is limited to the first eight block levels of the procedure's code. Before Getting Started: Before anything else, I suggest you make a backup copy of all the files in this package before using them. Store the backup copy in a safe place. Also, before running T-REF, you must run the program INITDB, which will create the database file needed for T-REF. Commitment: I have a strong commitment to the registered users of T-Ref. This package has been marketed as shareware and/or commercial software for over two years now. I have made over a dozen enhancements and corrections to it since its original version 1.0 release, some of which were made as suggestions from registered users. I am also committed to continuing the development of T-Ref further. I already have four more major enhancements slated for T-Ref over the next six months (by end of the year 1989). Included in this is a formatter, which will automatically reformat code to the styles selected by the user. Finally, if you experience any difficulties with running T- Ref, please let me know. I have made every effort to provide as bug-free of a program as possible, but know it is still not entirely perfected. I can only make the product better by getting good feedback from its users, registered or not. Also, if you have any ideas of how to make T-Ref better, I am always open to suggestions. Constructive criticism is always welcome! Sincerely, Jim D. Hart President, Synergy Software Solutions ii Chapter 1 - Introduction to T-Ref What T-Ref Can Do: T-Ref is actually two programs combined into a single package. First, it is a Source Lister for Borland's Turbo Pascal compiler (version 5.0). Of course, T-Ref's sophistication for listing the source files is far beyond just printing the source code. For example, along with the source listing, you can specify a line- by-line print-out of the lexical levels and the block levels, the active procedure or function of that line, and the line numbers along with the listing. Chapter 2 of this document describes in detail how to create a source listing to match your specific needs. The second part of T-Ref is the Cross Reference List, which was specifically designed to cross reference programs written for Borland's Turbo Pascal. It will give a complete cross reference of all identifiers declared within a program, or a partial listing (on requested object types). The listing gives each identifier's name, its type, the code line declared on, all lines referencing the names, and the scope (the procedure or function name and level in which the identifier was declared within). Chapter 3 describes how to print and interpret a cross reference listing. These two parts were designed to work in tandom: with just a few key strokes, you can get either a source listing, a cross reference listing, or both. Output can be routed to a specified output file or to the system's list device (printer). T-Ref is a syntax-scanning program, or simply a scanner (sometimes called a parser). The scanner performs associations between a program's source code and the language's grammar. This is to say that T-Ref understands the language structure (or syntax) of Turbo Pascal. It "scans" the input file for identi- fiers (first for their declarations and then for their uses) and stores the references made to them. However, T-Ref has one limi- tation in dealing with an input source file: it is not designed to recover from syntax errors found in the program and continue "scanning" the source. T-Ref can successfully scan a complete Turbo Pascal program file, a program "unit" file, or a declaration part of a program (usually kept in an "Include file"). The declaration part of a program may include a sequence of one or more of the following: label declarations, constant declarations, type declarations, variable declarations, and procedure and function declarations. (Like Turbo Pascal, there is no restrictions on order or fre- quency of each type of declaration.) Therefore, it is possible to scan a set of library procedures and functions placed in a separate file (accessed from the main program through the include file compiler directive) without having to scan any of the possibly many main programs that may use that library. T-Ref WILL NOT scan a sequence of code instructions alone. If you wish to retrieve a cross reference of only a code 1-1 sequence, you can enclose the code in a "BEGIN" ... "END." block and T-Ref will assume the code is a program. T-Ref's "Driver" Program: Almost all interactions you will make with the program will be done through the "driver" program (or shell) which appears when T-Ref begins execution. The main screen is divided into three major areas: the file I/O parameters, the source lister parameters, and the cross reference lister parameters. File I/O Area The File I/O parameters are used to specify the common directory and subdirectories names ("Active Directory"), the name of the file where the program to be parsed resides ("Active Input File"), and the name of the output file where the resulting listing is to be sent ("Active Output File"). The "Active Directory" parameter, when used, refers to the directory common to the input file, the output file, and all include files referenced within the input file (the program). The exception to this case is when the input or output file parameters begin with the "\" symbol or a drive symbol "d:". This is interpreted to mean "The specified file name includes the directory and possible subdirectories for the file's location." The Input File and Output File may also reference subdirec- tories within the directory (and subdirectories) specified by the Directory parameter. If a file name extension (file type) is not given in the input file parameter or the output file field, '.PAS' and '.PRT' are respectively assumed. T-Ref supports the capability to change the default file extension names. This is covered in Chapter 5 under "File Control". To send the output to the printer, just blank the 'Active Output File' parameter. To do this, position the block cursor at that parameter and strike the SPACE key. The parameter will be replaced with "--->> Printer" to signify the output is being routed to the printer. Finally, you can use the asterisk symbol (*) in the Active Output File parameter to tell T-Ref to give the output file name the same name as the input file name. Source Lister Area The source lister area of the driver screen is used to select the options desired for a listing of the Pascal source code. Chapter 2 of this manual is devoted to describing this area in detail. 1-2 Cross Reference Lister Area The cross reference lister area of the driver screen is used to select the options for the cross reference listing. Chapter 3 of this manual is devoted to describing this area in detail. Function Keys: All ten of the IBM PC's function keys are used by T-Ref to perform specific functions within the program. These functions can be divided into five areas: help functions, header creation, I/O control, saving and retrieving parameter settings, and executing the "scanner" and "SCRIPT" programs. In this section, we discuss the first four; the last is covered later in this chapter. Pop-Up Help Functions There are three keys that activate the program's help windows: the F1 provides a function key synopsis, the F2 function key provides text descriptions of each of the main screen parameters, and the F7 key assists you in selecting the source file to be cross referenced. If you ever wish to know what any of the function keys do, the F1 key will provide a list of these functions. The F2 key is the help key for any of the parameters displayed on the main driver screen, as well as for the File Control, Printer Control, and Screen Control Window parameters. Through the use of 'Context Sensitive' help functions, when the F2 key is struck, the help window that appears on the screen will provide information specifically related to the parameter selected by the block cursor. This simplifies the learning process and requires less documentation support while using the program. The F7 key can be a great help in searching out specific file names. When you strike the F7 key, a special window appears and asks you to type in the name of the file to search. The MS- DOS wildcard characters "*" and "?" are allowed here. The default file name extension is taken from the name extension specified in the 'File Control Window' (see Chapter 5, "File Control" for more details). Once you have typed in the file name sequence, hit RETURN. You can then select the desired file with the arrow keys (Left, Right, Up, and Down) or Home or End keys and, by again hitting the RETURN key, T-Ref returns to the main screen automatically loading the selected file into the "Active Input File" parameter. Creating Headers The F3 and F4 function keys are used to create the page headers for the source listing and cross reference listing respectively. Chapter 4 covers in detail the procedures for creating and activating headers for the listings. 1-3 I/O Control As stated before, T-Ref was designed to be flexible in its control of many hardware I/O features of your system: the display system, the disk file system, and the printer device. The F5, F6, and F8 function keys provide a way to set up T-Ref to match your personal tastes, as well as inform T-Ref of your system's features. Chapter 5 of this manual is devoted to describing how to set up T-Ref to respond appropriately to your system. Saving/Retrieving Parameter Settings The F9 and F10 function keys are used to retrieve and save all of the parameters (as they are set) from (or to) the file called 'T-REF.DB'. This information includes all of the driver screen fields, the source and cross reference headers, and the special settings for I/O control. This version allows you to save only up to 2 different combinations of parameter settings. Each combination will have an associated database identifier (up to eight characters long). Whenever you wish to load or save the parameter settings, you do so with the database identifier. When you press either the F9 key (to retrieve a different combination of parameter settings) or the F10 key (to save the present parameter settings), two windows will appear on the screen. The window on the right will display the various key options available and a short description of each. The window on the left will list the database identifiers of all combinations available to either read from or write to depending on the function key struck. The save (or F10) function allows you to create one new entry. Simply move the block cursor to the position below the SYSTEM identifier. A ">" symbol will then appear signifying the need for a name. Type in the identifier you wish to use in association with the parameter settings and hit RETURN. At this point, you have only entered the name. Strike RETURN again and the combination will be saved. Changing the Parameter Settings: T-Ref's uniquely designed driver program simplifies the procedures in how to use it primarily because of the "switch- selectable" options it establishs for nearly every parameter option the program supports. By switch-selectable, we mean that you select the desired option for each parameter by placing the block cursor over the parameter and striking the SPACE bar. This action causes the driver to "switch" from option to option as the SPACE bar is struck. When the desired option appears in the block cursor, you are through. This eliminates having to remember complex or symbolic keystroke sequences to bring up desired options. By simply knowing how to move the block cursor about the screen (with the arrow keys, primarily) and that the SPACE bar is used to set the parameters, you have learned the most complex part of the program! 1-4 Exiting T-Ref: To exit the driver shell program, simply strike the ESC key. A window will appear asking if you are sure you wish to quit the program. If you do wish to quit, respond with a "Y". T-Ref also tracks on updates to any of the parameters since the last time the parameter settings were saved to the database file. If you have updated any of them, it will warn you that changes have occurred, and will ask if you wish to save the present parameter settings. Executing the "Scanner" Program: The key combination ALT-F9 together will cause the "Driver" program to load the "Scanner" program into memory and begin scanning the file specified in the "Active Input File" parameter at the top of the driver screen. The Scanner Window: The scanner window is divided into four areas: the source files area, the XREF files area, the messages area, and the free memory area. These are described below. Source Files Area The top third of the window is the Source File area and contains three fields: the input file name, the include file name, and the output file name. These fields are updated by the scanner as needed. The numbers that appear to the left of the first two as the scanning process occurs are the line numbers of the source code as they are read from the input files. XREF Files Area The middle of the window is the XREF Files area. However, because the shareware version of T-Ref does not support XREF files, this area will always be inactive. See Chapter 7 for details on what XREF files are. Message Area The message area is used to provide status information about the progress of the scanning. If an error is encountered in the syntax of the input file, the message describing the error is printed within this area. This area is also used to display final results of the output (number of lines read/number of identifiers cross referenced), as well as to receive responses from the user about T-Ref generated questions. 1-5 Memory Free Display At the bottom of the scanner window will appear a "Memory Free" message that gets updated regularly as the scanning progresses. This signifies the amount of dynamic memory remaining (in bytes) T-Ref has available for use. If this value should drop below 1000 bytes, the scanner will abort the scan process as it has no more memory to save information. 1-6 Chapter 2 - The Source Lister Activating the Source Lister: The Source Listing program is activated by positioning the block cursor over the 'Source Listing' parameter, and striking the SPACE bar until either the word "Continuous" or "Procedural" appears within the cursor. To deactivate the source lister, hit the SPACE bar until the word "OFF" appears. Where "Continuous" sends the source listing in a continuous stream, "Procedural" performs page breaks at the conclusion of each procedure or function. Parameter Options: The fifteen parameters that appear on the screen below the 'Source Listing' parameter relate to specific information to be included or not included in the source listing. They are all updated in the same manner as the 'Source Listing' parameter: by placing the block cursor over the parameter and striking the SPACE bar until the desired value appears within the cursor block. Reserved Words and Identifiers: The 'Reserved Words' parameters are used to tell the program how the reserved words are to be formatted to the output. In the first field, you specify one of four different formats: "UPPER" capitalizes all letters in the reserve word, "LOWER" prints in lower-case lettering, "FORML" follows formal naming conventions, and "AS IS" prints the letters unchanged. Figure 2-1 below gives examples of different reserved words and how the output would be formatted; the first column is how the reserved words would be hypothetically read from the input source file. In the second field, you specify whether special emphasizing is to be used when sending the source listing to a printer device. "ULine" causes all reserve words to be underlined; "DStrike" embolds the reserve words by double striking the characters; "Dbl&ULn" will force the printer to do both double strike and underline reserve words; and finally "Off" turns off the emphasizing function. The embolding option is only available when the output is directed to the printer. The 'Identifiers' parameter's function is similar to the 'Reserved Words' parameter's described above: it formats the style of lettering for all identifiers to that requested. The same four formatting styles listed above are available for this parameter. However, here we must describe a feature of the "FORML" format not mentioned above. Since the Turbo Pascal compiler allows the use of the underline symbol (_) within an identifier (to make the source code more readable), the "FORML" 2-1 style makes use of this: not only is the first letter in the identifier capitalized, but each letter following the underline symbol is capitalized as well. Therefore, 'hot_item' becomes 'Hot_Item', 'not_so_fast' becomes 'Not_So_Fast', and 'ab_ra_ca_da_bra' becomes 'Ab_Ra_Ca_Da_Bra'. Line Numbering: The 'Line Numbering" parameter provides several various ways to number the source code, printed to the left of each line of output: "Extended", "Relative", and "Procedural". "Extended" line numbering presents a one-column line counter, where each line of source increments the counter. This is the simplist style of numbering, and does not take into effect whether the source code is coming from the main input file or from an Include file. "Relative" line numbering is a two-column line counter. The first column is the line number of the "main" input file; the second column is the Include file line number. That is, the line numbering is relative to the file the source is coming from. The line number of the main input file is incremented for each line read from the 'Active Input File' as specified at the top of the main screen. When an include file compiler directive, such as '{$i this.prc}', is scanned from the main input file, the program will begin printing the include file source code starting immediately after printing the line in which the include file compiler directive is on. At this point (until the end of the include file is reached), the line number of the main input file will remain the same and the line number of the include file will begin incrementing in the second column (starting from 1). The line number of the include file is not printed when the program is reading from the main input file. "Procedural" line numbering is also a two-column line counter. The first column is the same as the "Extended" numbering (see above); and the second column is the line number within the active procedure. As a new procedure/function decla- ration begins, the second line counter resets and begins counting from 1 again. However, when the procedure/function declaration is complete, the line numbering reverts back to the line numbering counter of the encompassing procedure/function. Lexical Level Numbering: The 'Lexical Levels' parameter, when activated ("ON"), will print for each source line a value representing the lexical, or procedural, depth of the program. Therefore, as the program scans the beginning of a procedure or function, the lexical level of the program is incremented; the level is decremented when the procedure or function is exited. 2-2 Block Level Numbering: The 'Block Levels' parameter, when activated ("ON"), will print a value representing the structured statement depth within the procedure or function being scanned. The value is printed on each line of the output. Whenever a structured statement (e.g., the IF, the FOR, the REPEAT, the CASE, the WITH, the WHILE, or the compound BEGIN-END statement) is entered during the scan of the source code, the block depth of the procedure is incremented, and is decremented upon exiting the structured statement. Block Diagramming: In addition to the lexical and block level numbering for the source lister, this version provides the capabilities to diagram the blocking outlines of the source code. Similar to the block numbering, this is a graphical representation of the code blocks rather than a numeric one. Up to eight levels of blocks can be shown for each procedure or function. If the code extends beyond eight levels, only the first eight are blocked. Only specific statements activate a diagram block level. These include the compound statement (a BEGIN .. END block), the IF statements, the CASE statement, and the REPEAT .. UNTIL block. The WITH, the WHILE, and the FOR statements are designed to assume there is only a single substatement. If more than one statement is to be acted upon, a compound statement must be given, thereby activating a diagram block. Auto-Commenting: One of T-Ref's unique features is its auto-commenting capability. Pascal has been recognized in the recent past for its ineffective ability to mark its END reserved word with the statement that initiated the block the END goes with. More recent languages such as Ada and Modula-2 correct this problem to some degree by requiring that each END be supplimented with an additional reserved word (or identifier) matching that which beget the compound structure. There is often nothing more unnerving to a programmer reading source code to get confused over which END symbol goes with which structured statement. T-Ref can help to some degree with its auto-commenting feature. As T-Ref produces the source listing, if the auto- commenter is "On", it will automatically generate a comment after each END symbol it encounters to signify the structure type it goes with. The comments always begin with the symbols "{#" and end with the symbols "#}, and recognizes these symbol sequences as T-Ref generated comments when scanned from the input source file. Note: When the auto-commenter is activated, T-Ref will auto- matically eliminate all commented code placed between the "{#" and "#}" symbols (while generating new comments). Therefore, do not use these symbols to start and end your comment blocks. 2-3 Active Procedure/Function Fields: The first 'Active Procedures' parameter field, when acti- vated ("ON"), will print the name of the procedure or function (presently being scanned) to the right of the output source code. The name is enclosed in brackets (between '{' and '}') to increase the documentation effects of the source and to make it possible to recompile the output source. The second parameter field is the column width field, which sets the number of columns the program will read from the source (input) file. The range may be from 20 columns to 126 columns (which is the limitation set by the Turbo editor). When the first field is set to "Off", this value is completely ignored and the entire source line (up to 126 columns) is read and scanned. However, when the first field is set to "On", any text on the input source code lines beyond the specified column setting will be ignored by the scanner and will not be printed. Figure 2-5 below demonstrates this output. Note: The column width setting also defines the maximum column in the cross reference listing format. That is, the number of line references printed per line is determined by this value. Header Markers: Header markers are score marker lines printed at the top and the bottom of each page of source code and are used to determine column positioning of source code. 2-4 Chapter 3 - The Cross Reference Lister Activating the Reference Lister: The Cross Reference Lister is activated by positioning the block cursor over the 'Cross Reference' parameter and striking the SPACE bar until either the word "Comprehensive" or "Proce- dural" appears within the cursor block. When activated, the lister gives a cross reference listing of the specified types of identifiers and/or additional details such as a procedural table of contents and analysis on the code scanned. Selection of identifiers is determined by object type as described below. To deactivate the cross reference lister, hit the SPACE bar until the word "Off" appears. Note that the same procedure here is used to activate the cross reference lister as in the source lister described in Chapter 2 above. Like the source lister, the parameters that appear on the screen directly below the 'Cross Reference' parameter relate to what information is to be included in the cross reference listing, as well as setting a header, paging, and including Include Files. These parameters are updated in the same manner as those parameters in the source lister area: by placing the block cursor over the parameter and striking the SPACE bar until the desired parameter appears within the cursor. With the "Comprehensive" option, T-Ref waits until the entire source code has been scanned before printing the cross reference listing; that is, it is comprehensive. However, there are times when in scanning a very large unit, there is not enough computer memory available to hold all related cross referencing information until the entire unit or program has been scanned. The "Procedural" option has the advantage of having the cross referencing data grouped into packages consistent with the source. Identifier reference listings can be, therefore, easier to follow. With this option, a cross reference listing is printed at the exit of every procedure or function, and includes only those identifiers declared local to that procedure. Since a procedure's local identifiers have scopes only while the procedure declaring it is "active", all references will occur by the closure of the procedure's declaration. Once the identifiers and their references have been printed, memory can be released for later use by other declarations further on in the source listing. Detail Level: With T-Ref 4.0, it is possible to select one of three different levels of detail for the cross reference listing. For the numbering scheme, "1" is the most abridged listing, providing only the bare minimum of information about the identifiers and listing their references; while "3" is the most comprehensive. See the section below on what is listed for each level. 3-1 Object Selection: The second through sixth parameters below the "Cross Refer- encer" header are the five object categories T-Ref recognizes. (See Appendix A, "Definitions" for descriptions of the object types). Each of these object categories have two fields: the scope and usage fields. The scope field is used to determine the selection of ident- ifiers based upon whether they are declared within the scanned program or unit ("Local"). The "All" setting acts just as the "Local" setting does. The "None" setting skips listing any identifier of that object category. In addition to these options, local identifiers may be further broken into local public and local private. The "LclPbl" selects only the identifiers of that type that are local public; the "LclPvt" selects only those that are local private. The commercial version of T-Ref supports the additional option "Remote", which selects only those identifiers declared in other units that the scanned unit or program USES (imports). Since this version does not support XREF files, this option is not included. The usage parameter is used to determine the selection of identifiers based upon whether or not they have been referenced within the program (other than in their declarations). The "Used" setting will select for listing only identifiers of that object type that were actually used within the program. The "Unused" setting selects only those identifiers not referenced anywhere within its scope. The "All" setting selects identifiers declared of that object type irregardless of their use. Scan Within Conditional Compilation: This option is inactive for the shareware version. T-Ref will always scan in conditional code segments. Procedural Table Listing: T-Ref, in addition to the identifier listing, provides the option to print a procedural table of contents of all the proce- dures and functions declared within the scanning, along with their declaration page and line numbers as well as the lexical level number of the procedure. This portion of the listing is excellent for getting a general layout of a program, unit , or library. The names are indented according to the lexical (proce- dural) level, and external procedures/functions are noted. Finally, each procedure/function in the listing will have a file number reference. In a separate listing that follows the proce- dural mapping, a list of source file names, dates, and times used in the scanning is printed. File dates and times are retrieved from the DOS file date/time tag of the file's last update. The file number reference matches that in the procedural map, thus correlating each procedure to the source file it is declared within. 3-2 The file to procedure association will help to quickly locate the include files procedures are declared within. In addition, the dates can be used to determine the latest date of modification to the source code scanned by T-Ref. Code Analysis: Finally, the cross reference lister can print an analysis summation about the source scanned and the identifiers listed. This analysis includes five areas: a structured statements count, a commented percentages count, the total number of identifiers cross referenced, a break-out of the identifier count by object type and data type, and an identifier usage count. The structured statements count lists the number of each structured statement types encountered during the scan, which includes IF, FOR, CASE, WHILE, REPEAT, and GOTO statements. The commented percentages gives a text ratio of commented text to code text. In this count, blank characters are not counted. The identifier usage count lists the number of identifiers LISTED based on the number of times they were referenced. Note: Untyped formal parameter, label, procedure, unit, and program names have no data type associated with them and therefore will not be included in the data type totals. Undeclared Identifiers: This parameter allows you to control whether or not to include identifiers in the listing that were never declared. Such identifiers occur when scanning an Include File that refer- ences identifiers within its scope, but whose declarations occur outside the source's domain; or when scanning a unit that uses other units and their identifiers, but whose XREF files were never loaded. Interpreting the Reference listing: This section provides a detailed look at the identifier reference listing, and is designed to familiarize you with the formats and symbols used. Formats As described in the section on "Detail Levels" above, there are five levels of detail in the cross reference listing. Detail level "1" is the lowest and provides only minimal information about the identifiers, focusing primarily on providing a way to distinguish between identifiers with the same name and listing where they are used. As the formats go toward "3", more details are provided. The following are the formats of each of the detail levels. 3-3 The identifier listing header is the first lines for each identifier in the listing. Level 1: Name LLLL:SSSS . . . Level 2: Name Object_Type Data_Type Declared on line LLLL:SSSS [Unit = Unit_Name] Level 3: Name Object_Type Data_Type Declared on line LLLL:SSSS within Proc_Name (Lvl) [Unit = Unit_Name] where Name is the name of the identifier (up to 20 characters long), Object_Type is its object type, Data_Type is its data type, LLLL:SSSS is the line number (and possibly the subline number) of the declaration, Proc_Name is the procedure or func- tion name that the identifier is declared within (up to 20 char- acters long), Lvl is the lexical level of the procedure or func- tion within the scanned code. (The "System" level is lexical level zero, the program level is 1, and so on.) Unit_Name is the declaration unit's name (if different from the one being scanned) and File_Name is the name of the file the declaration occurred in (if different from the main source file). At levels 2 and 3, after the identifier's header, the lines that follow are the references to the identifier. The format is: LLLL:SSSS LLLL:SSSS LLLL:SSSS ..... If an identifier is listed in the cross reference listing but has no references, the following is printed rather than the line references: <<< Identifier not referenced. >>> Each reference line number may be preceeded by one of four symbols, which signify that the identifier was set to a specific value. These are the "*", "&", "L", and "C". "*" means the identifier was explicitly set to a value on that line of code. "&" means the same as "*", except that the identifier was set at a lexical (procedural) level BELOW the level of its decla- ration. This second symbol could mean that you are setting a variable within a procedure that is not supposed to change it. "L" is used to signify that the variable is set as a Loop counter. "C" signifies where a variable is set through a call to a procedure or function and the variable matches the procedure's parameter sequence as a "Variable Formal Parameter". 3-4 NOTE: T-Ref MUST know the declaration of the procedure or function being called with the variable's formal reference to know whether it is being set (by matching the reference with a variable formal parameter). If the procedure's declaration is in another unit, for example, T-Ref has no way of knowing whether the reference is by name or value, and thus no symbol will show up. T-Ref, in such cases, will always assume the reference is by value. 'Explicitly set' means that the variable or function was set with a "Variable := <<Expression>>" statement, and does not take into consideration setting the identifier through the use of procedure or function parameter passing. If the identifier was not declared within the source code (as is the case when cross referencing a portion of a program or a library or procedures that reference identifiers in other portions of the program), then the reference number line rather reads: "Not declared within the scanned source." Symbols The object type field will be one of the following: "Undefnd"- Undefined (Not declared within the parsed code) "Label" - Labels "Constnt" - Constants "ScalVal" - Scalar Values "Typed C" - Typed Constants "Type" - Types "Var" - Variables "FrmParm" - Formal Parameters (considered a Variable) "VarParm" - Variable Formal Parameters (considered a Variable) "Rec Fld" - Record Fields "Rec Tag" - Record Fields declared as Record Tags "Program" - Program name "Procedr" - Procedures "Functn" - Functions The data type field will be one of the following: "Undefnd" - Undefined "Integer" - Integer scalars "Sht Int" - Short Integer scalars "Lng Int" - Long Integer scalars "Byte" - Byte scalars "Word" - Word scalars "Real" - Real scalars "Single" - Single Precision Real "Double" - Double Precision Real 3-5 "Extnded" - Extended Real "Comp" - Comp Real "Boolean" - Boolean scalars "String" - String scalars "Char" - Character scalars "Scalar" - User Defined Scalars "Pointer" - Pointer Type "Range" - Subranges "Record" - Structured Type Records "Proced" - Procedural Type and may be preceeded by some combination of the following to signify a structured data type: "Absolute Addr" - The Variable is located at a specific address in memory "Pointer to" - The Type or Variable is of type Pointer "File of" - The Type or Variable is of type File "Set of" - The Constant, Type, or Variable is of type Set For example, "Absolute Addr Set of Scalar" means the data type of the identifier is a set of type scalar and is at a specific address in memory. "Hardwired" Identifiers: Although the standard TYPE identifiers such as BOOLEAN, INTEGER, and REAL are part of the SYSTEM.TPU unit, T-Ref considers these identifiers "wired" into the compiler itself. Such identifiers are part of the language's foundation. Thus, you will never get a "listing" with these identifiers in them. 3-6 Chapter 4 - Common Features This chapter highlights the features T-Ref possesses that were not discussed in the previous two chapters but whose param- eters option are visible on the main screen. These features are common to both the source lister and the cross reference lister. Handling Include Files: T-Ref offers a unique and flexible way of handling Turbo Pascal include files when these compiler directives are encoun- tered in the input source code. The 'Read Include File' param- eter for the source listing informs the program whether or not to list the source code of the external files (included during compilation through an include file compiler directive) with the main source code. When activated ("YES"), include files are automatically placed into the output's source listing immediately after the source line containing the include file compiler directive is printed. Besides the "YES" and "NO" options, there is an OPTIONAL setting ("OPT") which allows you to selectively decide which include files are to be printed. When this setting is selected, a message is sent to the message area of the Scanner screen every time an include file compiler directive is scanned, asking whether or not the file is to be included in the source listing. Responding "Y"es will route the include file source to the output; "N"o will cause the include file source listing to be skipped. The 'Read Include File' parameter for the cross reference lister is used to tell the program whether or not to include external source files in the cross reference listing. When activated ("Yes"), include files are automatically parsed for cross referencing identifiers within the files (declarations and uses) based on the object type settings of the cross reference parameters. The OPTIONAL setting ("Opt") allows you to selec- tively choose the files to be included in the cross referencing process. Defining Listing Headers: To further enhance the source and cross reference listings, the program implements powerful page header options. Rather than defining the header within the source code, the headers are created using special pop-up windows. The source lister and cross reference lister each have their own header windows. The 'Header' parameters for both the source listing and the cross reference listing are handled in precisely the same manner. These parameters, when activated ("ON"), print a preset text header at the top of each page of output (either source or cross reference, respectively). The header is from one to five lines and each line can be up to 75 columns in length. The F3 and F4 function keys are used to set up the header text. 4-1 Creating Headers By striking the F3 function key (for the source listing header) or the F4 function key (for the cross reference listing header), a window will appear on the screen, giving the present header line size and asking if you wish to change it. After responding with the number of lines for the header (from 1 to 5 lines), or by entering RETURN to keep the same number, the program will display two windows. The window on the bottom will show all key options available in the header window; the one on the top is the text editor window, used to type in the header format. It is possible to add information into the header dyna- mically. That is file name, page number, and present date and time strings can be inserted directly into the header. Thus, you can create your own page numbering layout if you wish to have page numbering at the top of the page rather than at the bottom with the page numbering T-Ref provides. Note: If 0 (zero) is entered as the number of lines, it in effect eliminates printing the header without actually destroying the text within the header itself. In this case, the text editor window will not appear. Activating Headers To activate printing the headers, simply move the block cursor to the appropriate 'Header' field and set it to "On" by striking the SPACE bar. There is a 'Header' field within both the source listing and the cross reference listing areas. When headers are active, the top margin setting is still used to determine the spacing at the top of the page before the header is printed. However, when a header is printed, the program will automatically buffer two blank lines after the header (before the next line of source code or cross reference listing information), so it is not necessary to buffer the header with blank lines within the header itself. Page Numbering: The 'Page Numbering' parameters will, when activated ("ON"), automatically number the pages of the output source (whether it is going to a file or to the printer). A date/time tag (which comes from reading the system clock for the present date and time) is also printed on the page number line, along with the name of the main source file. 4-2 Chapter 5 - I/O Control Features In addition to the many parameters visible on the main screen, there are a number of others available through the func- tion keys and are used to set various system options, primarily dealing with controlling the computer's Input/Output. This chapter details some of the features of T-REF, version 5.0, added to make it more flexible and easier to use. More precisely, these features are the parameters dealing with the screen (F5 key), the printer (F6 key), and the file input/output (F8 key). The F2 context-sensitive help function is supported with these three windows. You can get a synopsis of each of the fields by bringing up any of the windows, placing the cursor over one of the fields, and striking the F2 key. Screen Control: Several parameters have been added to T-REF so that various aspects of the color display screen may be controlled. This allows you to set the colors that are pleasing to your eyes. In addition, for those users that have color graphics boards (CGA or EGA) running with monochrome displays, you may wish to set the color options to all black and white screens, since T-Ref has no way of knowing what form of monitor is attached (only the display mode). These parameters are displayed and changed by first striking the F5 function key. Since these options only effect color display systems, if you have a monochrome system or an EGA system running in monochrome mode, these options are not available. CGA Snow If you have a CGA board that produces snow during direct screen writes, set this parameter to "Yes" by striking the SPACE bar until it appears in the block cursor. If your board does not create snow, set it to "No". If you do not know if your monitor creates snow, you can test your system by setting the parameter to "???" and striking the RETURN key. A few second test will begin in which characters are written to the screen. If you do not see snow before the beep (indicating the end of the test), your system does not produce snow. You can then set the param- eter to the appropriate setting. You cannot exit this feature while this parameter is set to the test mode ("???"). Color Selectors The remaining parameters are used to specify colors to be used by T-REF for both the main screen and for all windows. The main screen foreground and background colors are the colors to be used on the main T-REF screen. The Exit Frame Color is used to specify the color of the CGA/EGA/VGA frame area upon exiting T- Ref. When the Exit Frame Color is Black, it also prevents setting the frame color upon start-up of the program. 5-1 The remaining six parameters define the colors for the pop- up windows that are created when the function keys are pressed. The frame is the border around the window; the title is the title given to the window; and the text is the area inside the window. Printer Control: The printer control feature (brought up with the F6 key) provides several important options to control the printer. Printer Port The first selects the printer port, which can be LPT1, LPT2, LPT3, COM1, or COM2. The LPT ports are the line printer ports (parallel ports 1, 2, and 3), while the COM ports are serial ports 1 and 2. In almost all cases, you should be using "LPT1". However, some printers may be configured to other computer ports on the computer. When one of the parallel (LPT) ports is selected, T-Ref will check the printer device port for a ready signal for each line of text sent to the printer. If it ever receives a "not ready" response, it will generate an error. The COM printer ports are NOT tested for "ready" signals like the LPT ports. The output is shipped to the port byte by byte. Lines Per Page The second parameter sets the number of lines per page for both the source lister and the cross reference lister output. The page length is set to a default value of 66 (which is normal for most printers using 11 inch paper lengths and 6 lines per inch). If you have a printer that prints in compressed line formats or uses legal size paper, for example, you will want to change this value. The range is from 10 to 255. Top, Bottom, and Left Margins It is possible to specify the number of lines of margin for output at the top and at the bottom of each page. Both of these parameters may be set to any value from 0 to 9. The top margin is the number of lines skipped before the first printable line on the page (including the header if it is specified). The bottom margin is the number of blank lines after the last printable line on the page. This may be the page number line if page numbering is activated. The Left Margin setting allows you to tell T-Ref how many columns in from the left side to buffer the output. Values are from 0 to 20. Printer Column Width Many printers will automatically perform a carriage return/ line feed when a print line exceeds its maximum column width, then finishes printing the text on the next line. Since T-Ref 5-2 cannot intrinsically know when this happens, "page creeping" occurs. By setting this value, T-Ref will perform the carriage return/line feed operation for the printer; thus preventing not only page creeping, but page run-off as well. Note however, that this setting is different based on the printer mode. That is, the Elite printer width is not the same as the Pica printer width or the Compressed printer width. Make sure you set this value to match the appropriate mode your printer will be printing in! Printer Sequences The last two parameters are used to send start and end command sequences to the printer in order to change printer modes. It is, for example, possible to send commands to your printer to initially set it into "compressed" or "draft" mode before printing begins and to return it back to the previous set mode after the printing is complete. Several ASCII symbols represent special characters in the command sequence: "^", "@", and "#". The carrot symbol "^" is used to send a CONTROL character (i.e., "^R" sends a one char- acter code of "CTRL R"). The actual ASCII character values sent range from 1 ("^A") to 26 ("^Z"), as well as 27 ("^["), 28 ("^\"), and 29 ("^]"). Only the capitalized alpha characters are allowed to follow the "^" symbol (A-Z). The ampersand "@" denotes the ESCAPE character which is a common character in sending commands to the printer. For example, "@M" would send a two character command code "ESC M", and "@@@" would send a two character command code "ESC @". The pound symbol "#" tells T-REF to send a specific ASCII character to the printer. The three numeric characters following the pound symbol is the decimal value of the ASCII character. For example, "#027" sends an ESC character; "#097" sends the letter "A". It is important to remember that the numeric char- acter sequence ("0" through "9") following the "#" symbol must be three characters long. Important Notes 1) Do not place blanks or other characters into the sequence to separate different commands in the sequence. The characters (except for the special characters described above) are sent just as they are typed in. 2) The three special characters ("^", "@", "#") can be sent by typing the character twice in sequence. Example To set an EPSON FX into Elite mode at the start of the print and to put it into PICA at the end, your commands would be: Start Printer Sequence: @M End Printer Sequence: @P 5-3 File Control: The file control feature (enabled with the F8 key) performs three basic functions: it allows you to enter a specific file path string, to specify the desired default file extension names to be used by T-Ref, and to specify whether to create and/or read XREF files during the source scan. (NOTE: XREF files are not included as part of the shareware version of T-Ref so these fields are inactive for this version.) File Path T-Ref contains full DOS PATH string support in locating all relevant files, whether it is a T-Ref file (like "T-REF.DB" or "T-REF.HLP") or a scan file (like an Include file or XREF file). However, in searching for scan files, it is possible to override the DOS PATH string with this option. The file path string works the same as the DOS PATH command does. By entering a series of directory file paths (separated by semicolons), you can have T-Ref search the list for files not found on the default drive and directory. Directories may be absolute or relative to the default DOS directories. For example: @FRAME TEXT = \PROJECTS;C:\BACKUP\TP4;FILESRCH\SOURCE;B:..\TOOLS specifies four different directories other than the default drive and directory. The first two are absolute. "\PROJECTS" refers to a subdirectory from the root directory of the default drive. "C:\BACKUP\TP4" refers to the subdirectory "BACKUP\TP4" from the root directory of drive C. The last two paths are subdirectories relative to the default directories. "FILESRCH\SOURCE" is a subdirectory located within the present default drive and directory. "B:..\TOOLS" refers to a subdirectory "TOOLS" of the parent directory of the default directory on drive B. If the path string is left blank, T-REF will read the PATH specification passed by DOS and use that as the path string. In addition, you can load the DOS PATH string with the CTRL-R key sequence. If you desire, you can then edit the character string and save it. File Extension Names The file extension default string parameters allow you to change the extension defaults. These strings determine the name extensions of files to be read from (such as in "Source Input") or written to (such as "Source Output", "XREF Unit File", and "XREF Include File"). The "Source Input" and "Source Output" extension deal solely with the "Active Input File" and "Active Output File" parameters respectively on the main screen. When file extensions are not included in those parameters, they default to those designated here. (Like the Turbo Pascal compiler, if a file extension is not given for Include file compiler directives and USES unit 5-4 files, '.PAS' is always assumed.) The XREF Unit and Include File extensions tell T-REF what file extension names are to be given to the identifier (XREF) files generated when T-REF scans Units and Include files. However, XREF files are not supported with this version, so changing these extension strings will have no effect on the execution of T-Ref. Read Unit XREF Files Inactive for this version. Creating XREF Files Inactive for this version. 5-5 Chapter 6 - T-Ref Quick Start This chapter is meant to help familiarizing you with T-Ref and guide you in setting up the T-Ref system to best fit your personal needs and system hardware. I suggest that you follow the first step in this chapter (making a backup copy of the T-Ref program package) before ever running the program. Once you have done this, you can either perform the remaining steps immediately or any time later. Those remaining steps will assist you in how to instruct T-Ref of your system's hardware. Backing Up T-Ref: Immediately after opening your T-Ref package, you should make at least one copy of the entire disk. The program is not copy-protected, so all that is necessary is a "COPY s:*.* t:" command, where 's:' is the source drive the enclosed diskette is on and 't:' is the target drive the blank formatted diskette is on. After completing the copy process, put the original disk in a safe place. If anything happens to your copy, you still have the original to make additional copies from. Building the Database File: Next, run the program called INITDB. This program will create the database file you will use for saving and retrieving your parameter settings. The file created by this program is called T-REF.DB. After running the program, verify this file now exists. Executing T-Ref: Running the main driver is as simple as typing T-REF at the DOS command line. The program will load and the "driver" screen (see Chapter 1, "T-Ref's Driver Program") will appear. Note the block cursor is at the 'Active Directory' field, which is presently blank. Setting the Default Parameters: When T-Ref loads, one of the first actions it performs is to load one of the database's combination of parameter settings into memory. 6-1 I/O Control Features a) Screen Control Parameters The very next step once the driver shell is loaded should be to set the various color attributes that you like to work with (if you have a color or EGA monitor card) and to tell T-Ref whether your CGA produces "snow" during memory contentions. If you have a monochrome monitor card and monochrome monitor, you can skip this step. For more on the color selections and "snow" settings, see Chapter 5, "Screen Control". b) Printer Control Parameters You will need to give T-Ref information about your printer. Through the 'Printer Control Window', set the proper printer port for your system, the number of lines per page your printer supports, and the margins that you most likely will use. See Chapter 5, "Printer Control" for more details. The number of lines per page will most likely be 66 (6 lines per inch times 11 inches). If your printer supports other than standard printing characteristics, set the value appropriately. Also, set the printer column width to the most common setting. Remember that some printers can have different printer column maximum widths based on the printer mode (i.e., Elite, Pica, Compressed, etc.). Set this based on the most common mode you will be printing in. Finally, if you plan on printing most often in a mode other than the one the printer is normally in, you will need to specify a start and end printer command sequence. Use your printer manual to determine the command codes your printer accepts. c) File Control Parameters Next, under the 'File Control Window', you need to decide whether or not to enter a directory PATH string for T-Ref to use. If you have your source code organized into only a few direc- tories, you may wish to enter the PATHs to them. If you have different directories for each project or program you are devel- oping, you may wish to leave this field blank and enter the PATHs for each project individually. Source Lister Options In the Source Lister area of the driver shell, you should decide which word formats you will want most often for reserved words and identifiers. If you wish to create a generic header template for the source lister, now would be the time to do so. Strike the F3 key for the source lister header window. You may, for example, wish to put your name, company, address, copyright statements, and even determine file name and present date/time locations in the header. See chapter 4 for more on setting up headers. 6-2 In addition, you should set the 'Active Procedure/Function' column width field to the maximum input width of the normal source code (see Chapter 2, "Active Procedure/Function"). Cross Reference Lister Options In the Reference Lister area of the driver shell, you may wish to set the detail level and your most frequently used object selection parameter settings. Like the source lister, you may wish to create a generic header template for the cross reference lister. Use the F4 key to bring up the header window and enter the text and dynamic fields as you did with the source lister. Saving the New Settings: Once you have gotten to this point, you are ready to save the settings to the database file. Strike the F10 key. When the 'Write Database' window appears, make sure the block cursor is over the selector "SYSTEM" (option 0). Then hit RETURN. Now, each time T-Ref is called and the default SYSTEM combination is loaded, the settings you have saved will be loaded. 6-3 Chapter 7 - Commercial Version of T-Ref In this chapter, I will describe the differences between the shareware version of T-Ref which you are using and the commercial version of T-Ref which is available at the $45 level of regis- tration. The T-Ref Shell: There are very few differences between the commercial version of T-Ref and the shareware version. Many of the selec- tion restrictions are obviously removed to provide the additional features of the commercial version. Scripting One benefit gained is the scripting feature offered with the commercial version. With this feature, you can automatically scan a sequence of files by passing the name of a file containing the source file names, rather than the source itself. Thus, you can quickly produce printable source and cross reference listings with a single command. Extended Database Set The commercial version supports the ability to save up to 10 combinations of parameter settings, where the shareware version only allows 2. Printer Hold File It is possible with the commercial version to route the output from the scan to a printer hold file, which, in addition to the normal text, contains printer commands, page ejects, and other information used to manipulate the printer. From the hold file, you just simply need to perform a PRINT or COPY command to send the file to the printer. (This is especially nice when you wish to generate the output on one computer, and print the files from another.) PRINT Interface DOS 3.X provides a resident utility called PRINT, which among other things, allows you to submit files for printing to a print spooler. The resident utility then maintains the list of files that need to be printed, and performs this action in the background. The commercial version of T-Ref can directly interface with the PRINT utility by creating a print file and then submitting the file for printing. Thus, you can continue to scan other files while printing occurs in the background, and you are no longer restricted to the speed of your printer. 7-1 The Scanner Program: Calling the Scanner from DOS The commercial version of T-Ref supports the feature of directly calling the scanner program from DOS, rather from the T- Ref shell. This provides the scanner with the addition memory that the shell program normally takes up. When calling the scanner from the DOS line, you pass in the name used to identify the database parameter set saved. The scanner then loads the database, and executes the scan automatically. XRU and XRI files Definitely the most unique feature of T-Ref is its ability to not only scan files for listing purposes, but to also create identifier files about the identifiers found during the course of the scan. Once created, these identifier files can then be "linked" into other scans and the identifiers that would appear (through the use of the USES clause for example) become available for referencing. XRU files are created from Unit Files, and contain all of the identifiers declared in the INTERFACE portion of the unit. T-Ref can then be told to LINK such files into the scan of other units when references to those units are encountered in the USES clause of the scanning unit. Benefits from such a feature include more accurate infor- mation about the use of variables. For example, with XRU files linked, T-Ref ALWAYS knows when variables are set by procedural calls and the variable is passed as a parameter. Also, decla- rations from TYPEs declared in other units are more accurate. XRI files are created from Include Files, and once created, can be linked into other source files that reference them rather than having to continuously scan them. Linking occurs in seconds while having to scan them over and over takes minutes. The commercial version includes XRU files already created for all of the identifiers found in the Turbo Pascal unit library: DOS, CRT, PRINTER, GRAPH, TURBO3, GRAPH3, and OVERLAY. The Source Lister: Graphics Block Diagramming As an alternative to the ASCII style of block diagramming, the commercial version also provides a GRAPHICS style. This option uses the IBM extended character set to produce the block diagrams. The Cross Referencer: 7-2 Detail Levels 4 and 5 Even the shareware maximum level 3 does not actually show all of the information T-Ref can produce about the source scanned. The commercial version supports levels 4 and 5 as well. At levels 4 and 5, associated file names are given with the declaration, as well as with the references. References are also grouped by the procedures of the references. Various warnings and notes are also listed with the references. There are 5 different warnings T-Ref generates about the scanned code and two notes. Warnings include flagging when variable formal parameters are never set, when functions are never set, when loop variables are set within the loop block, when variables are not set before their use, and when forward declared functions/procedures are never fully declared. Notes include when formal parameters are set to a value and when recursive, inline, interrupt, far, and external procedures or functions are declared. Remote Identifier Listing With the use of cross reference (XRU) files generated by T- Ref, it is possible to load and list references to identifiers declared in other units. Scanning Conditionals The commercial version of T-Ref can also be told to act exactly like the Turbo compiler in how it sees the source code it is scanning. The compiler will ignore certain portions of the code when conditional statements are encountered on the input. T-Ref can be told to act just the same, skipping over whatever code resides within conditionals. T-Ref does this by tracking on what conditional symbols are defined and takes appropriate action when encountering the IFDEF, IFNDEF, and IFOPT directives. Conditionals and Compiler Directive listings Included in the cross reference listings of the commercial version are the conditional listing and the compiler directive listing. In the conditional listing, T-Ref lists all of the conditional symbols found during the scan. From the listing, you can determine on what lines the symbols were DEFINE'd and UNDEF'ined, as well as what lines they were referenced. The compiler directive listing lists all of the compiler directives found during the scan, the lines referenced, and a "+" or "-" symbol (where appropriate) corresponding to their being turned ON or OFF respectively. 7-3